manual: signature option for caml_example #1702
Conversation
|
I am not sure whether the |
|
For more concrete example, I finished the conversion of the example in ocamldoc: html and pdf . (The corresponding commit also fixes transf.mll to make sure that \camlexample is considered a verbatim mode).
In this case, it would show the wrapping module type, I can see two options to avoid this case: either require to combine the signature mode with |
|
Yes, the first option is simplest, and inferred signatures are not very useful anyway (they mostly repeat the signature). Would you consider adding a Changes entry, though? This is a nice change that did require some work from you, and I like the idea of crediting changes to the manual and broader documentation ecosystem. |
There was a problem hiding this comment.
Approved -- although I understand that you might want to make further tweaks. Feel free to merge whenever you are ready and the CI passes.
(This change caught other mistakes in the ocamldoc manual than the ones caught by Leo, which means that it was indeed a reasonable idea.)
| && mv $*.transf_error.tex $*.gen.tex\ | ||
| && $(TEXQUOTE) < $*.gen.tex > $*.texquote_error.tex\ | ||
| && mv $*.texquote_error.tex $*.tex\ | ||
| || printf "Failure when generating %s\n" $*.tex |
There was a problem hiding this comment.
We are accumulating logic to use CAMLLATEX/TRANSF/TEXQUOTE in several different Makefiles (apparently cmds/Makefile does not use CAMLLATEX but only the other two?). Maybe it would make sense to factorize this in a shared makefile, or as a separate shellscript to invoke?
There was a problem hiding this comment.
This is probably a good idea for a next PR.
Octachron
force-pushed
the
manual_signature_example
branch
from
e1168ed
to
cc8bb43
Compare
|
I added an error message for the combination of |
Octachron
force-pushed
the
manual_signature_example
branch
from
cc8bb43
to
b0cb561
Compare
|
I think we could keep this in 4.07, as it could be useful for further improve-the-manual changes (eg. a more complete version of #1209) that it could be worthwhile to include in 4.07 documentation. The present PR does not touch anything that is critical for the release preparation/testing, and it is customary to give external tools (ocamldoc, the manual build tools) more slack in freeze decisions. |
Octachron
force-pushed
the
manual_signature_example
branch
from
b0cb561
to
5918e4e
Compare
|
It is true that this is mostly a validation tool. I moved back the change entry to 4.07 . |
manual/manual/cmds/Makefile
Outdated
| @@ -12,9 +12,14 @@ TRANSF=$(SET_LD_PATH) $(OCAMLRUN) ../../tools/transf | |||
| TEXQUOTE=../../tools/texquote2 | |||
| FORMAT=../../tools/format-intf | |||
|
|
|||
| WITH_TRANSF= ocamldoc.tex top.tex intf-c.tex flambda.tex spacetime.tex \ | |||
| CAMLLATEX= $(OCAMLRUN) ../../tools/caml-tex2 -caml "TERM=norepeat $(OCAML)" \ | |||
| -n 80 -v false | |||
There was a problem hiding this comment.
Does this not need an update to take 482e8a8 into account?
There was a problem hiding this comment.
You are totally right, I had forgotten this point. I should try to make my test environment sensitive to this problem. Fixed.
|
I removed a wandering unused macros, since keeeping the macro count as low as possible seemed important enough to warrant a last minute fix. I will squash and merge once the CI passes. |
* Signature option for caml_example
* convert ocamldoc code example to caml_example
* error message when using caml_example*{signature} without *
|
Cherry-picked to 4.07 as d040ad6 |
This small PR extends the options of the
caml_examplepseudo-environment with a signature mode. With this PR, the possible modes for caml_example are:toplevel, for examples that should look as if they were send to the toplevelverbatim, for generic code examplessignature, for examples of interface files or signatureThis seems to cover most documentation needs in the manual, and it is sufficient to convert the faulty example fixed by @lpw25 in #1693 .
In term of implementation, the code inside the environment is merely wraped inside
module type Wrap = sig ... endbefore being send to the ocaml subprocess.